<!DOCTYPE HTML>

<html>
  <head>
    <title>Life File Formats Documentation</title>
    <style type="text/css">
      mark {
        background-color: #ff7;
      }
      aside {
        font-style: italic;
      }
      .indent {
        margin-left: 3em;
      }
      h1 {
        font-size: 200%;
      }
      h2 {
        font-size: 150%;
      }
      header {
        font-size: 200%;
        font-weight: bold;
        font-style: italic;
        text-align: center;
      }
      footer {
        font-size: 80%;
        font-weight: normal;
        font-style: italic;
        border-top: 1px silver solid;
        padding-top: 0.25em;
      }
    </style>
  </head>

  <body>

    <header>
      Cellular Automata File Formats
    </header>

    <section>
      <h1>Contents</h1>
      <ul>
        <li>
          <a href="#intro">Introduction</a>
        </li>
        <li>
          <a href="#rle">Run Length Encoded (RLE)</a>
        </li>
        <li>
          <a href="#life-105">Life 1.05 &amp; XLife 2.0</a>
        </li>
        <li>
          <a href="#life-106">Life 1.06</a>
        </li>
        <li>
          <a href="#plaintext">Plaintext</a>
        </li>
        <li>
          <a href="#ya-life">Ya-Life</a>
        </li>
      </ul>
    </section>

    <section id="intro">
      <h1>Introduction</h1>
      <p>
        This document describes some of the file formats used for Game of Life
        and Life-like programs.
      </p>
      <p>
        Content was assembled from various parts of the internet. Some was
        copied or modified from the MCell <a
          href="http://psoup.math.wisc.edu/mcell/ca_files_formats.html"
        >Cellular Automata file formats</a> page.
      </p>
    </section>

    <section id="rle">
      <h1>Run Length Encoded (RLE)</h1>
      <p>
        This file is in text format. Lines must not exceed 70 characters
        although it is recommended that reader can handle more than this.
        End of line markers can be in any of the Unix, DOS/Windows or Mac
        styles.
      </p>
      <p>
        There are four distinct sections of the file. In order they are:
      </p>
      <ol>
        <li># lines</li>
        <li>Header line</li>
        <li>Pattern lines</li>
        <li>Comments</li>
      </ol>
      <h2># lines</h2>
      <p>
        # lines begin with <kbd>#</kbd> followed a letter indicating the type of
        information the line provides. They are:
      </p>
      <dl>
        <dt><kbd>C</kbd></dt>
        <dd>
          <div>
            Indicates that a line of comment follows. Example:
          </div>
          <pre class="indent">#C Lorem ipsum dolor sit amet</pre>
        </dd>
        <dt><kbd>c</kbd>
        <dd>
          Same as C.
        </dd>
        <dt><kbd>N</kbd></dt>
        <dd>
          <div>
            The name of the pattern. Example:
          </div>
          <pre class="indent">#N My pattern</pre>
        </dd>
        <dt><kbd>O</kbd></dt>
        <dd>
          <div>
            Says when and by whom the file was created. Example:
          </div>
          <pre class="indent">#O John Smith john.smith@example.com Fri Apr 30 19:38:52 2012</pre>
        </dd>
        <dt><kbd>P</kbd></dt>
        <dd>
          <div>
            Specifies the coordinates of the top left corner of the patten. Quite
            what this means is unclear. This is an enhancement used by Life32
            and the advice is it is best ignored.
          </div>
          <pre class="indent">#P 90 136</pre>
        </dd>
        <dl><kbd>R</kbd></dl>
        <dd>
          <div>
            Gives the coordinates of the top-left corner of the pattern relative
            to the centre of the grid. Example:
          </div>
          <pre class="indent">#R -22 -57</pre>
        </dd>
        <dl><kbd>r</kbd></dl>
        <dd>
          <div>
            Gives the rules for the pattern in S/B format. The standard method
            of representing rules is in the <em>header line</em> (below), but
            this form is sometimes used instead. Example:
          </div>
          <pre class="indent">#r 23/3</pre>
        </dd>
      </dl>
      <h2>Header line</h2>
      <p>
        The header line has the form:
      </p>
      <pre class="indent">x = m, y = n, rule = Baaa/Sbbb</pre>
      <p>
        <kbd>x</kbd>, <kbd>y</kbd> and <kbd>rule</kbd> are literal strings.
        <kbd>m</kbd> and <kbd>n</kbd> are numbers giving the width and height of
        the pattern, respectively. <kbd>Baaa/Sbbb</kbd> is the rule's
        designation in the form birth-rule/survival rule. <kbd>aaa</kbd> and
        <kbd>bbb</kbd> are strings of digits from 0 to 8 while <kbd>B</kbd> and
        <kbd>S</kbd> are literal characters.
      </p>
      <p>
        The <kbd>rule</kbd> part may be omitted, in which case the comma
        preceding it is also omitted. Where no rule is given <a
          href="http://www.conwaylife.com/wiki/Conway%27s_Game_of_Life"
        >Conway's Life</a> (B3/S23) is assumed.
      </p>
      <h2>Pattern lines</h2>
      <p>
        A description of the pattern begins on the line following the header
        line. It is encoded as a sequence if items of the form
      </p>
      <pre class="indent">&lt;run_count&gt;&lt;tag&gt;</pre>
      </p>
      <p>
        &lt;tag&gt; is one of the following:
      </p>
      <dl>
        <dt><kbd>b</kbd></dt>
        <dd>a dead cell</dd>
        <dt><kbd>o</kbd></dt>
        <dd>a live cell</dd>
        <dt><kbd>$</kbd></dt>
        <dd>end of a line of the pattern</dd>
      </dl>
      <p>
        <kbd>&lt;run_count&gt;</kbd> is the number of occurrences of
        <kbd>&lt;tag&gt;</kbd> and can be omitted if is equal to 1.
      </p>
      <p>
        The last <kbd>&lt;run_count&gt;&lt;tag&gt;</kbd> pair is followed by a
        <kbd>!</kbd> character. Dead cells at the end of a pattern line do not
        need to be encoded and neither does the end of the last line of the
        pattern.
      </p>
      <p>
        Whitespace is permitted between <kbd>&lt;run_count&gt;&lt;tag&gt;</kbd>
        items and before the terminating <kbd>!</kbd>. It is not permitted to
        place whitespace in the middle of a
        <kbd>&lt;run_count&gt;&lt;tag&gt;</kbd> item, although readers should be
        able to handle this.
      </p>
      <h2>Comments</h2>
      <p>
        Anything after the final <kbd>!</kbd> is ignored and can be used for
        comments. However <kbd>#C</kbd> lines are more usually used for this
        purpose (see above).
      </p>
    </section>

    <section id="life-105">
      <h1>Life 1.05 &amp; XLife 2.0</h1>
      <p>
        The XLife 2.0 file format is closely related to Life 1.05 and differs
        from it only slightly. The following text describes Life 1.05 with any
        differences in XLife 2.0 noted.
      </p>
      <p>
        This is an ASCII text format. Lines may not exceed 80 characters.
        End of line is denoted by the MS-DOS / Windows format of CR followed by
        LF. Files usually have the <kbd>.LIF</kbd> extension or <kbd>.life</kbd>
        for XLife 2.0.
      </p>
      <p>
        The first line of the file is a header that identifies the format. It
        is:
      </p>
      <pre class="indent">#Life 1.05</pre>
      <p>
        After the header are optional description lines which begin with
        <kbd>#D</kbd> in Life 1.05 or <kbd>#C</kbd> in XLife 2.0. This is
        followed by no more than 78 characters of text. Leading and trailing
        spaces are ignored. For example, the following two lines are equivalent:
      </p>
      <pre class="indent">#D Lorem ipsum dolor sit amet
#D    Lorem ipsum dolor sit amet</pre>
      <p>
        There should be no more than 22 <kbd>#D</kbd>  lines in the
        file.
      </p>
      <p>
        Next comes an optional rule specification. If no rules are specified
        the pattern will run with whatever rule the Life program is currently
        using. There are two forms of the rule specification:
      </p>
      <dl>
        <dt>
          <kbd>#R</kbd>
        </dt>
        <dd>
          This specifies the required rule in S/B format. For example
          <kbd>#R&nbsp;23/3</kbd> for <a
            href="http://www.conwaylife.com/wiki/Conway%27s_Game_of_Life"
          >Conway's Life</a> or
          <kbd>#R&nbsp;23/36</kbd> for <a
            href="http://en.wikipedia.org/wiki/HighLife"
          >HighLife</a>.
        </dd>
        <dl>
          <kbd>#N</kbd>
        </dl>
        <dd>
          <kbd>#N</kbd> appears on its own and is simply a short way of
          specifying <a
            href="http://www.conwaylife.com/wiki/Conway%27s_Game_of_Life"
          >Conway's Life</a>. It is equivalent to <kbd>#R&nbsp;23/3</kbd>.
        </dd>
      </dl>
      <p>
        The next part of the file contains information about the cells. There is
        one or more &quot;cell blocks&quot;.
      </p>
      <p>
        Each cell block starts with a <kbd>#P</kbd> line, where the
        <kbd>#P</kbd> is followed by the (x,y) coordinates of the upper left
        hand corner of the cell block, where (0,0) is the center of the current
        window to the Life universe. For example <kbd>#P&nbsp;-1 4</kbd>.
      </p>
      <p>
        The <kbd>#P</kbd> line is followed by one of more lines that define the
        state of the cells in the block. Each line describes a row of the block
        with <kbd>.</kbd> (a dot) representing an &quot;off&quot; cell and
        <kbd>*</kbd> representing &quot;on&quot;.
      </p>
      <p>
        Blank lines are represented by a single <kbd>.</kbd> (dot). Any other
        line may truncate all dots to the right of the last <kbd>*</kbd>. Any
        blank line is ignored.
      </p>
      <p>
        There is no limit to the number of lines in a cell block, but the file's
        80 character width limit applies to the row width.
      </p>
    </section>

    <section id="life-106">
      <h1>Life 1.06</h1>
      <p>
        This is an ASCII file format that simply lists the coordinates of the
        alive cells.
      </p>
      <aside>
        <p>
          File size can be very large for large patterns.
        </p>
      </aside>
      <p>
        The file begins with the following header line:
      </p>
      <pre class="indent">#Life 1.06</pre>
      <p>
        Immediately after the header is the list of the coordinates of on cells
        in the form <kbd>x&nbsp;y</kbd>. Each coordinate is placed on its own
        line.
      </p>
    </section>

    <section id="plaintext">
      <h1>Plaintext</h1>
      <p>
        This is an ASCII file format with no restriction on line length.
      </p>
      <p>
        The file begins with comment lines which begin with <kbd>!</kbd>. Some
        command lines are special and begin with a &quot;keyword&quot;. These
        are:
      </p>
      <dl>
        <dt><kbd>!Name:</kbd></dt>
        <dd>
          <div>The name of the pattern. For example:</div>
          <pre class="indent">!Name: My pattern</pre>
        </dd>
        <dt><kbd>!Author:</kbd></dt>
        <dd>
          <div>The name of the pattern author. For example:</div>
          <pre class="indent">!Author: John Smith</pre>
        </dd>
      </dl>
      <p>
        All other comment lines are read literally. For example:
      </p>
      <pre class="indent">! Lorem ipsum dolor sit amet</pre>
      <p>
        Empty comment lines, with just a single <kbd>!</kbd> are permitted.
      </p>
      <p>
        The description of the pattern follows the last comment line. Each line
        of the file describes a row of the pattern with a <kbd>.</kbd> (dot)
        representing an &quot;off&quot; cell and an <kbd>O</kbd> (capital letter
        &quot;o&quot;) for an &quot;on&quot; cell.
      </p>
      <p>
        Any trailing &quot;off&quot; cells may be omitted from a line. Blank
        rows are indicated by blank lines.
      </p>
    </section>

    <section id="ya-life">
      <h1>Ya-Life</h1>
      <p>
        This is the native file format for YaLife. It is encoded in UTF-8 with
        byte order mark. End of line is denoted by any of CR, LF or CRLF. There
        is no restriction on the length of any line.
      </p>
      <p>
        A YaLife file is in three parts, a header that identifies the file
        format, a meta-data section followed by the pattern data. Blank lines
        may occur anywhere in the file and are ignored.
      </p>
      <h2>Header</h2>
      <p>
        The first line of the file identifies its type. It is always:
      </p>
      <pre class="indent">== ya-life 1 ==</pre>
      <h2>Meta data</h2>
      <p>
        The file begins with one or more meta data commands, each of which
        occupies a line of text. All commands begin with an exclamation mark (!)
        and are followed immediately by one or more spaces. The supported
        commands are:
      </p>
      <dl>
        <dt><kbd>!Name</kbd></dt>
        <dd>
          <div>The name of the pattern. For example:</div>
          <pre class="indent">!Name My pattern</pre>
        </dd>
        <dt><kbd>!Author</kbd></dt>
        <dd>
          <div>The name of the pattern author. For example:</div>
          <pre class="indent">!Author John Smith</pre>
        </dd>
<!--
        <dt><kbd>!URL</kbd></dt>
        <dd>
          <div>The URL of any related web resource. For example:</div>
          <pre class="indent">!URL http://www.example.com/my-pattern.html</pre>
        </dd>
        <dt><kbd>!Date</kbd></dt>
        <dd>
          <div>The date and (optionally) time that the pattern was created. This
          may be the date the pattern was discovered or just the date the file
          was saved. Dates should be in the format
          <kbd>YYYY/MM/DD hh:mm:ss.ms</kbd>. The time component can be omitted.
          The seconds / milliseconds component can also be omitted. Dates /
          times should be in UTC / GMT. For example:
          </div>
          <pre class="indent">!Date 2012/05/14
!Date 2012/05/14 15:09
!Date 2012/05/14 15:09:37
!Date 2012/05/14 15:09:37.56</pre>
        </dd>
-->
        <dt><kbd>!Rule</kbd></dt>
        <dd>
          <div>Specifies the required rule in either S/B or B/S format. If the
          Life program's current rule is to be used either the <kbd>!Rule</kbd>
          command can be omitted or the value <kbd>default</kbd> can be used for
          clarity. For example:</div>
          <pre class="indent">!Rule 23/3
!Rule B3/S23
!Rule default</pre>
        </dd>
        <dt><kbd>!Size</kbd></dt>
        <dd>
          <div>Specifies the total size of the pattern(s) in the form
          <kbd>width&nbsp;height</kbd>. No pattern data should exceed these
          bounds. For example:</div>
          <pre class="indent">!Size 24 39</pre>
        </dd>
        <dt><kbd>!</kbd></dt>
        <dd>
          <div><kbd>!</kbd> on its own, followed by at least one space is used
          for descriptive comments. There may by any number of such comments.
          Leading and trailing spaces are ignored. Empty comment lines are
          ignored. Example:</div>
          <pre class="indent">! Lorem ipsum dolor sit amet.
!
! Ut enim ad minim veniam.</pre>
        </dd>
      </dl>
      <p>
        Of these commands only <kbd>!Size</kbd> is compulsory.
      </p>
      <h2>Pattern Data</h2>
      <p>
        After the last command comes a list of pattern definitions. Each
        definition occupies two lines. The first line specifies the offset of
        the pattern from the top left hand corner of the grid, with the Y-axis
        running downwards. The second line contains a run-length encoded
        representation of the pattern. There must be at least one pattern
        definition in the file.
      </p>
      <p>
        The offset is specified by a space separated pair of non-negative
        numbers followed by a new line.
      </p>
      <p>
        The encoded cell data is a repeated sequence of items of the form
        <kbd>&ltrun-count&gt;&lt;tag&gt;</kbd>.
      </p>
      <p>
        <kbd>&lt;tag&gt;</kbd> is one of the following:
      </p>
      <dl>
        <dt><kbd>.</kbd> (dot)</dt>
        <dd>a dead cell</dd>
        <dt><kbd>*</kbd> (asterisk)</dt>
        <dd>a live cell</dd>
        <dt><kbd>#</kbd></dt>
        <dd>end of row marker</dd>
      </dl>
      <p>
        <kbd>&ltrun-count&gt;</kbd> is the number of occurences of
        <kbd>&lt;tag&gt;</kbd> in hexadecimal. If <kbd>&ltrun-count&gt;</kbd> is
        one it is omitted.
      </p>
      <p>
        Whitespace is not permitted anywhere in the
        <kbd>&ltrun-count&gt;&lt;tag&gt;</kbd> sequence, all of which must be on
        the same line.
      </p>
      <p>
        End-of-row markers may be omitted from the end of the sequence.
        Similarly dead cell sequences may be omitted before end-of-row markers
        or the end of the sequence. This means that readers must assumes all
        cells are dead by default.
      </p>
      <p>
        Example pattern data:
      </p>
      <pre class="indent">10 12
2.a5*.2*#a*3#.*</pre>
      <p>
    </section>

    <footer>
      Copyright &copy; 2012, Peter Johnson <a
        href="http://www.delphidabbler.com/"
      >www.delphidabbler.com</a>.
    </footer>
  </body>
</html>
